Google Git
Sign in
chromium / external / gitster / git-htmldocs / dcc6495c1f9fcf63dde4f602c75ded45145a7237 / . / git-bisect.html
blob: 5df54707e0fb4ab147f9f3c46e820d1ddf4ed0c1 [file] [log] [blame]
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano7ccb9fd2006-07-15 01:38:40[diff] [blame]6<meta name="generator" content="AsciiDoc 7.0.2" />
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
19a { color: blue; }
20a:visited { color: fuchsia; }
21
22em {
23 font-style: italic;
24}
25
26strong {
27 font-weight: bold;
28}
29
30tt {
31 color: navy;
32}
33
34h1, h2, h3, h4, h5, h6 {
35 color: #527bbd;
36 font-family: sans-serif;
37 margin-top: 1.2em;
38 margin-bottom: 0.5em;
39 line-height: 1.3;
40}
41
42h1 {
43 border-bottom: 2px solid silver;
44}
45h2 {
46 border-bottom: 2px solid silver;
47 padding-top: 0.5em;
48}
49
50div.sectionbody {
51 font-family: serif;
52 margin-left: 0;
53}
54
55hr {
56 border: 1px solid silver;
57}
58
59p {
60 margin-top: 0.5em;
61 margin-bottom: 0.5em;
62}
63
64pre {
65 padding: 0;
66 margin: 0;
67}
68
69span#author {
70 color: #527bbd;
71 font-family: sans-serif;
72 font-weight: bold;
73 font-size: 1.2em;
74}
75span#email {
76}
77span#revision {
78 font-family: sans-serif;
79}
80
81div#footer {
82 font-family: sans-serif;
83 font-size: small;
84 border-top: 2px solid silver;
85 padding-top: 0.5em;
86 margin-top: 4.0em;
87}
88div#footer-text {
89 float: left;
90 padding-bottom: 0.5em;
91}
92div#footer-badges {
93 float: right;
94 padding-bottom: 0.5em;
95}
96
97div#preamble,
98div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
99div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
100div.admonitionblock {
101 margin-right: 10%;
102 margin-top: 1.5em;
103 margin-bottom: 1.5em;
104}
105div.admonitionblock {
106 margin-top: 2.5em;
107 margin-bottom: 2.5em;
108}
109
110div.content { /* Block element content. */
111 padding: 0;
112}
113
114/* Block element titles. */
115div.title, caption.title {
116 font-family: sans-serif;
117 font-weight: bold;
118 text-align: left;
119 margin-top: 1.0em;
120 margin-bottom: 0.5em;
121}
122div.title + * {
123 margin-top: 0;
124}
125
126td div.title:first-child {
127 margin-top: 0.0em;
128}
129div.content div.title:first-child {
130 margin-top: 0.0em;
131}
132div.content + div.title {
133 margin-top: 0.0em;
134}
135
136div.sidebarblock > div.content {
137 background: #ffffee;
138 border: 1px solid silver;
139 padding: 0.5em;
140}
141
142div.listingblock > div.content {
143 border: 1px solid silver;
144 background: #f4f4f4;
145 padding: 0.5em;
146}
147
148div.quoteblock > div.content {
149 padding-left: 2.0em;
150}
151div.quoteblock .attribution {
152 text-align: right;
153}
154
155div.admonitionblock .icon {
156 vertical-align: top;
157 font-size: 1.1em;
158 font-weight: bold;
159 text-decoration: underline;
160 color: #527bbd;
161 padding-right: 0.5em;
162}
163div.admonitionblock td.content {
164 padding-left: 0.5em;
165 border-left: 2px solid silver;
166}
167
168div.exampleblock > div.content {
169 border-left: 2px solid silver;
170 padding: 0.5em;
171}
172
173div.verseblock div.content {
174 white-space: pre;
175}
176
177div.imageblock div.content { padding-left: 0; }
178div.imageblock img { border: 1px solid silver; }
179span.image img { border-style: none; }
180
181dl {
182 margin-top: 0.8em;
183 margin-bottom: 0.8em;
184}
185dt {
186 margin-top: 0.5em;
187 margin-bottom: 0;
188 font-style: italic;
189}
190dd > *:first-child {
191 margin-top: 0;
192}
193
194ul, ol {
195 list-style-position: outside;
196}
197ol.olist2 {
198 list-style-type: lower-alpha;
199}
200
201div.tableblock > table {
202 border-color: #527bbd;
203 border-width: 3px;
204}
205thead {
206 font-family: sans-serif;
207 font-weight: bold;
208}
209tfoot {
210 font-weight: bold;
211}
212
213div.hlist {
214 margin-top: 0.8em;
215 margin-bottom: 0.8em;
216}
217td.hlist1 {
218 vertical-align: top;
219 font-style: italic;
220 padding-right: 0.8em;
221}
222td.hlist2 {
223 vertical-align: top;
224}
225
226@media print {
227 div#footer-badges { display: none; }
228}
229include::./stylesheets/xhtml11-manpage.css[]
230/* Workarounds for IE6's broken and incomplete CSS2. */
231
232div.sidebar-content {
233 background: #ffffee;
234 border: 1px solid silver;
235 padding: 0.5em;
236}
237div.sidebar-title, div.image-title {
238 font-family: sans-serif;
239 font-weight: bold;
240 margin-top: 0.0em;
241 margin-bottom: 0.5em;
242}
243
244div.listingblock div.content {
245 border: 1px solid silver;
246 background: #f4f4f4;
247 padding: 0.5em;
248}
249
250div.quoteblock-content {
251 padding-left: 2.0em;
252}
253
254div.exampleblock-content {
255 border-left: 2px solid silver;
256 padding-left: 0.5em;
257}
258</style>
259<title>git-bisect(1)</title>
260</head>
261<body>
262<div id="header">
263<h1>
264git-bisect(1) Manual Page
265</h1>
266<h2>NAME</h2>
267<div class="sectionbody">
268<p>git-bisect -
Junio C Hamano7c73c662007-01-19 00:37:50[diff] [blame]269 Find the change that introduced a bug by binary search
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]270</p>
271</div>
272</div>
273<h2>SYNOPSIS</h2>
274<div class="sectionbody">
275<p><em>git bisect</em> &lt;subcommand&gt; &lt;options&gt;</p>
276</div>
277<h2>DESCRIPTION</h2>
278<div class="sectionbody">
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]279<p>The command takes various subcommands, and different options depending
280on the subcommand:</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]281<div class="literalblock">
282<div class="content">
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]283<pre><tt>git bisect start [&lt;bad&gt; [&lt;good&gt;...]] [--] [&lt;paths&gt;...]
Junio C Hamano1974bf22007-10-31 05:57:20[diff] [blame]284git bisect bad [&lt;rev&gt;]
285git bisect good [&lt;rev&gt;...]
286git bisect skip [&lt;rev&gt;...]
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]287git bisect reset [&lt;branch&gt;]
288git bisect visualize
289git bisect replay &lt;logfile&gt;
Junio C Hamanof440a232007-03-23 10:46:17[diff] [blame]290git bisect log
291git bisect run &lt;cmd&gt;...</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]292</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]293<p>This command uses <em>git-rev-list --bisect</em> option to help drive the
294binary search process to find which change introduced a bug, given an
295old "good" commit object name and a later "bad" commit object name.</p>
296<h3>Basic bisect commands: start, bad, good</h3>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]297<p>The way you use it is:</p>
298<div class="listingblock">
299<div class="content">
300<pre><tt>$ git bisect start
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]301$ git bisect bad # Current version is bad
302$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
303 # tested that was good</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]304</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]305<p>When you give at least one bad and one good versions, it will bisect
306the revision tree and say something like:</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]307<div class="listingblock">
308<div class="content">
309<pre><tt>Bisecting: 675 revisions left to test after this</tt></pre>
310</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]311<p>and check out the state in the middle. Now, compile that kernel, and
312boot it. Now, let's say that this booted kernel works fine, then just
313do</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]314<div class="listingblock">
315<div class="content">
316<pre><tt>$ git bisect good # this one is good</tt></pre>
317</div></div>
318<p>which will now say</p>
319<div class="listingblock">
320<div class="content">
321<pre><tt>Bisecting: 337 revisions left to test after this</tt></pre>
322</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]323<p>and you continue along, compiling that one, testing it, and depending
324on whether it is good or bad, you say "git bisect good" or "git bisect
325bad", and ask for the next bisection.</p>
326<p>Until you have no more left, and you'll have been left with the first
327bad kernel rev in "refs/bisect/bad".</p>
328<h3>Bisect reset</h3>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]329<p>Oh, and then after you want to reset to the original head, do a</p>
330<div class="listingblock">
331<div class="content">
332<pre><tt>$ git bisect reset</tt></pre>
333</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]334<p>to get back to the master branch, instead of being in one of the
335bisection branches ("git bisect start" will do that for you too,
336actually: it will reset the bisection state, and before it does that
337it checks that you're not using some old bisection branch).</p>
338<h3>Bisect visualize</h3>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]339<p>During the bisection process, you can say</p>
340<div class="listingblock">
341<div class="content">
342<pre><tt>$ git bisect visualize</tt></pre>
343</div></div>
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]344<p>to see the currently remaining suspects in <tt>gitk</tt>. <tt>visualize</tt> is a bit
345too long to type and <tt>view</tt> is provided as a synonym.</p>
346<p>If <tt>DISPLAY</tt> environment variable is not set, <tt>git log</tt> is used
347instead. You can even give command line options such as <tt>-p</tt> and
348<tt>--stat</tt>.</p>
349<div class="listingblock">
350<div class="content">
351<pre><tt>$ git bisect view --stat</tt></pre>
352</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]353<h3>Bisect log and bisect replay</h3>
354<p>The good/bad input is logged, and</p>
355<div class="listingblock">
356<div class="content">
357<pre><tt>$ git bisect log</tt></pre>
358</div></div>
359<p>shows what you have done so far. You can truncate its output somewhere
360and save it in a file, and run</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]361<div class="listingblock">
362<div class="content">
363<pre><tt>$ git bisect replay that-file</tt></pre>
364</div></div>
365<p>if you find later you made a mistake telling good/bad about a
366revision.</p>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]367<h3>Avoiding to test a commit</h3>
368<p>If in a middle of bisect session, you know what the bisect suggested
369to try next is not a good one to test (e.g. the change the commit
370introduces is known not to work in your environment and you know it
371does not have anything to do with the bug you are chasing), you may
372want to find a near-by commit and try that instead.</p>
373<p>It goes something like this:</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]374<div class="listingblock">
375<div class="content">
376<pre><tt>$ git bisect good/bad # previous round was good/bad.
377Bisecting: 337 revisions left to test after this
378$ git bisect visualize # oops, that is uninteresting.
379$ git reset --hard HEAD~3 # try 3 revs before what
380 # was suggested</tt></pre>
381</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]382<p>Then compile and test the one you chose to try. After that, tell
383bisect what the result was as usual.</p>
Junio C Hamano1974bf22007-10-31 05:57:20[diff] [blame]384<h3>Bisect skip</h3>
385<p>Instead of choosing by yourself a nearby commit, you may just want git
386to do it for you using:</p>
387<div class="listingblock">
388<div class="content">
389<pre><tt>$ git bisect skip # Current version cannot be tested</tt></pre>
390</div></div>
391<p>But computing the commit to test may be slower afterwards and git may
392eventually not be able to tell the first bad among a bad and one or
393more "skip"ped commits.</p>
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]394<h3>Cutting down bisection by giving more parameters to bisect start</h3>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]395<p>You can further cut down the number of trials if you know what part of
396the tree is involved in the problem you are tracking down, by giving
397paths parameters when you say <tt>bisect start</tt>, like this:</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]398<div class="listingblock">
399<div class="content">
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]400<pre><tt>$ git bisect start -- arch/i386 include/asm-i386</tt></pre>
401</div></div>
402<p>If you know beforehand more than one good commits, you can narrow the
403bisect space down without doing the whole tree checkout every time you
404give good commits. You give the bad revision immediately after <tt>start</tt>
405and then you give all the good revisions you have:</p>
406<div class="listingblock">
407<div class="content">
408<pre><tt>$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
409 # v2.6.20-rc6 is bad
410 # v2.6.20-rc4 and v2.6.20-rc1 are good</tt></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]411</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]412<h3>Bisect run</h3>
413<p>If you have a script that can tell if the current source code is good
414or bad, you can automatically bisect using:</p>
Junio C Hamanof440a232007-03-23 10:46:17[diff] [blame]415<div class="listingblock">
416<div class="content">
417<pre><tt>$ git bisect run my_script</tt></pre>
418</div></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]419<p>Note that the "run" script (<tt>my_script</tt> in the above example) should
Junio C Hamano1974bf22007-10-31 05:57:20[diff] [blame]420exit with code 0 in case the current source code is good. Exit with a
421code between 1 and 127 (inclusive), except 125, if the current
422source code is bad.</p>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]423<p>Any other exit code will abort the automatic bisect process. (A
424program that does "exit(-1)" leaves $? = 255, see exit(3) manual page,
425the value is chopped with "&amp; 0377".)</p>
Junio C Hamano1974bf22007-10-31 05:57:20[diff] [blame]426<p>The special exit code 125 should be used when the current source code
427cannot be tested. If the "run" script exits with this code, the current
428revision will be skipped, see <tt>git bisect skip</tt> above.</p>
Junio C Hamanof440a232007-03-23 10:46:17[diff] [blame]429<p>You may often find that during bisect you want to have near-constant
430tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
431"revision that does not have this commit needs this patch applied to
432work around other problem this bisection is not interested in")
433applied to the revision being tested.</p>
434<p>To cope with such a situation, after the inner git-bisect finds the
435next revision to test, with the "run" script, you can apply that tweak
436before compiling, run the real test, and after the test decides if the
437revision (possibly with the needed tweaks) passed the test, rewind the
438tree to the pristine state. Finally the "run" script can exit with
439the status of the real test to let "git bisect run" command loop to
440know the outcome.</p>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]441</div>
442<h2>Author</h2>
443<div class="sectionbody">
444<p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;</p>
445</div>
446<h2>Documentation</h2>
447<div class="sectionbody">
448<p>Documentation by Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p>
449</div>
450<h2>GIT</h2>
451<div class="sectionbody">
452<p>Part of the <a href="git.html">git(7)</a> suite</p>
453</div>
454<div id="footer">
455<div id="footer-text">
Junio C Hamano35738e82008-01-07 07:55:46[diff] [blame]456Last updated 07-Jan-2008 07:50:02 UTC
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]457</div>
458</div>
459</body>
460</html>